.\" t
.\" -*- nroff -*-
.\"
.\" Copyright (c) 2001 Leon Bottou, Yann Le Cun, Patrick Haffner,
.\"                    AT&T Corp., and Lizardtech, Inc.
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual. Otherwise check the web site
.\" of the Free Software Foundation at http://www.fsf.org.
.TH NSDEJAVU 1 "1/4/2007" "DjView-4" "DjView-4"
.de SS
.SH \\0\\0\\0\\$*
..
.SH NAME
nsdejavu \- DjVu browser plugin

.SH SYNOPSIS
.B PLUGINSDIR/NSDEJAVUSO

.SH WARNING
Using
.B nsdejavu
as a plugin in 2020 is very difficult because
popular browsers either do not support netscape plugins (chrome), or
removed support for netscape plugins other than flash (firefox).
We regret this decision because djview/nsdejavu is a perfect
example of very well behaved plugin that would have been
easy to support.

.SH DESCRIPTION
The shared library
.B NSDEJAVUSO
uses the Netscape browser plugin
.SM API
to display DjVu images in
in a number of popular web browsers.
It works by invoking
a standalone viewer out-of-process
with the special command line option
.BR -netscape .
The plugin first searches a program named
.BR djview .
If this program cannot be found,
it searches for
.BR djview4
and finally
.BR djview3.
It is always possible to override this search strategy
by setting the environment variable
.B NPX_DJVIEW
to the full path of the desired executable.


.SH MIME TYPES AND EXTENSIONS
Typing the
.SM URL
of a recognized DjVu document in your web browser
should automatically invoke the DjVu browser plugin.
Each browser uses different methods to determine that a particular
.SM URL
is in fact a DjVu document.
Web server normally provide a
.SM MIME
type to web browsers.
The official 
.SM MIME 
type for DjVu documents is
.BR image/vnd.djvu .
For compatibility with ancient versions of the
DjVu viewer, it is common to use instead the
experimental 
.SM MIME 
type
.B image/x-djvu
or
.BR image/x.djvu .
Web servers should be configured to send the 
proper
.SM MIME 
type for DjVu documents. 
Most web browsers also recognize files ending with
.B .djvu
or
.B .djv
as DjVu files.

An easy way to check if an http server is giving an appropriate
content-type is to invoke the following command with a 
.SM URL
corresponding to an actual DjVu file on the server.
.IP "" 2
.BI "curl -u " URL " | grep Content-Type"
.PP
The result should be one of the following, preferably the first.
.IP "" 2
.B Content-Type: image/vnd.djvu
.br
.B Content-Type: image/x.djvu
.br
.B Content-Type: image/x-djvu
.PP
Any other 
.SM MIME 
type indicates a server misconfiguration.


.SH CGI-STYLE FLAGS
The behavior of the DjVu browser plugin can be specified
by augmenting the
.SM URL
using a syntax similar to that used by the
.SM CGI
programs.
This syntax is described by the following template:
.IP "" 3
.BI "http://.../file.djvu?djvuopts&" "keyword=value" "&" "keyword=value" "&" "..."
.PP
The DjVu browser plugin only recognizes keywords that appear
after the word
.BR djvuopts .
The keywords recognized by each viewer
are listed in the corresponding man page. 
Unrecognized keywords are ignored.
The most common keywords are:
.TP
.BI page= pagename
Specify which page is displayed by name or by ordinal number.
.TP
.BI zoom= zoomfactor
Set the zoom factor. 
Legal values for
.I zoomfactor
are:
.br
.TS
center,box;
lfI l
lfB l
lfB l
lfB l
lfB l
.
number	Magnification factor in range 10% to 999%.
one2one	Select the "one-to-one" mode.
width	Select the "fit width" mode.
page	Select the "fit page" mode.
stretch	Stretch the image to the plugin window size.
.TE


.SH BROWSER COMPATIBILITY
The DjVu browser plugin has been tested with several popular web browsers:
Netscape 4 and 6; Gecko based browsers such as Mozilla, Galeon and Firefox;
KHTML based browsers such as Konqueror; and Opera.
Please read the browser documentation to find out where 
the plugin library should be installed.


.SH EMBEDDING DJVU IMAGES IN HTML PAGES
You can integrate DjVu content on an
.SM HTML
web page with either the
.SM <embed>
or the
.SM <object>
tag.
This method will work even if your web 
server does not support the DjVu
.SM MIME
type.
The
.SM CGI
style flags can be directly used as attributes of the embedding tag.
The following example shows the W3C standard syntax with the
.SM OBJECT 
tag:
.IP "" 3
.B "<object data=""myfile.djvu"" type=""image/vnd.djvu"""
.br
.B "\0\0\0\0\0\0\0\0\0 width=""100%"" height=""100%"" >"
.br
.B "\0\0\0 <param name=""page"" value=""iii"">"
.br
.B "\0\0\0 <param name=""zoom"" value=""stretch"">"
.br
.B "\0\0\0 This browser cannot render djvu data."
.br
.B "</object>"
.PP
And this is the customary syntax with the
.SM EMBED
tag:
.IP "" 3
.B "<embed src=""myfile.djvu"" type=""image/vnd.djvu"""
.br
.B "\0\0\0\0\0\0\0\0\0 width=""100%"" height=""100%"""
.br
.B "\0\0\0\0\0\0\0\0\0 page=""iii"" zoom=""stretch""></embed>"
.PP



.SH INTERFACING THE DJVIEW PLUGIN WITH JAVASCRIPT
Recent versions of the 
.B djview4
plugin can be controlled from the JavaScript interpreter of 
browsers implementing the Mozilla NPRuntime API.
To access the plugin object,
include the attribute
.BI "id=""" pluginname """"
into the
.B <object>
or
.B <embed>
tag and use the JavaScript function
.BI "getElementById(""" pluginname """)."
.PP
The plugin object implements two methods
to retrieve and set the value of the options
usually recognized as CGI-style flags.
It also can evaluate a specified JavaScript
expression whenever something changes
in the status of the djview interface.
.TP
.IB "pluginobject" ".setdjvuopt(""" key """," value ")"
Set the value of the djvu option
.I key
to the character string
.IR value .
This achieves the same effect as specifying option
.IR key = value
among the CGI-style flags.  
For instance, values of the key
.B page
can be page IDs, page titles, page numbers, or page names.
.TP
.IB "pluginobject" ".getdjvuopt(""" key """)"
Return the value of the djvu option
.I key
as a string.
The returned value is always a character string, 
even when the return is logically a number.
Boolean values are returned as strings
.B yes
or 
.BR no. 
Besides the usual CGI-style flags,
this function recognizes the additional key 
.B pages
and returns the total number of pages in the DjVu document.
An empty string is returned when the key is not recognized.
.TP
.IB "pluginobject" ".onchange=""" code """;"
Ensure that string
.I code
is evaluated in the context of the plugin object
whenever something changes in the djview graphical 
user interface.  For instance, this evaluation happens
when progressive refinements are painted, and
when the user manipulates the image interactively.
.TP
.IB "pluginobject" ".version"
Return a string describing the plugin version.
This property can be used to test whether the
djview plugin is scriptable in this browser.
.PP
Note that the scriptability feature may not 
be accessible until the djview plugin is fully loaded.
Therefore it is advisable to check
.IB "pluginobject" ".version"
from the JavaScript
.B onload
before calling any other method.

.SH CREDITS
This program was written by Andrei Erofeev <andrew_erofeev@yahoo.com>
and was then improved by Bill Riemers <docbill@sourceforge.net> and
L\('eon Bottou <leonb@users.sourceforge.net>.

.SH SEE ALSO
.BR djvu (1),
.BR ddjvu (1),
.BR djview4 (1)
